🔗 Jira Ticket

CMG-997

📋 PR Type

• ✨ Feature
• 🐛 Bug Fix
• 🔥 Hotfix
• ♻️ Refactor
• 🧹 Chore / Dependency Update
• 📝 Documentation

📝 Description

What changed?

New "Map Entry" step (delta migration, iteration 2+)

• Split the migration flow into 6 steps from iteration 2 onwards: Legacy CMS → Destination Stack → Map Content Fields → Map Entry → Test Migration → Execute. Iteration 1 stays the original 5-step flow (no Map Entry).
• Step 3 (Map Content Fields) now shows only new content types (not migrated in the previous iteration) — re-mapping already-migrated types risks data loss.
• Step 4 (Map Entry) is a new standalone screen that shows only already-migrated content types that have entry mappings, and lets the user select entries to update.

Single-route, filter-based content type fetch

• getContentTypes takes a filter query param (new | old) instead of a new endpoint. On iteration 2+ it diffs the current vs previous iteration's contentTypesMapper.json by otherCmsUid to return the new-only or old-only slice. Iteration 1 is untouched.
• Map Entry list excludes content types with no entryMapping, and derives each content type's status icon (green "Updated" / blue "Mapped") from the saved isUpdate state so it persists correctly across reloads.

Iteration-aware step numbering

• Backend current_step state machine is now iteration-aware (DELTA_STEPPER_STEPS adds Map Entry as step 4, shifting Testing → 5, Execute → 6 on delta iterations).
• Frontend stepper, CTA button states, step gates (project_current_step), and the side-nav (migrationSteps.json) all resolve step numbers by iteration.

Stepper / navigation fixes

• Step completion is driven by the persisted current_step, so navigating back to review a completed step no longer resets the progress bar, and completed steps stay navigable.
• Restart resets the progress bar correctly; the Start Migration button is disabled via the actual API call (not the completion flag) so live logs still stream.
• Friendlier empty state on delta iterations ("No new content types — you can still continue") with the Continue button enabled and the "Go to Legacy CMS" action hidden.

Bug fix — entry update data loss

• removeEntriesFromDatabase previously deleted every entry present in the entry mapper, even ones never migrated (no contentstackEntryUid), silently dropping them. Now it only removes entries that already exist in Contentstack (have a contentstackEntryUid); isUpdate ones are collected for update, the rest are left to be created fresh.

Tests

• Added unit tests for the updateEntryCli service (basic-auth & OAuth paths, missing stack key, auth errors, stdout/stderr log-level classification, non-zero exit handling, warning mapping).

Why?

Delta (re-)migrations need to map and update entries of already-migrated content types across iterations without losing data or re-mapping content that was already migrated. The previous flow had no Map Entry step, no iteration-aware step numbering, and a bug that dropped never-migrated entries during update.

🧩 Affected Areas

• api — Node.js backend
• ui — React frontend
• upload-api — Upload API server
• docker / docker-compose
• CI / GitHub Actions workflows
• Environment variables / config
• Other:

🧪 How to Test

Iteration 1 (fresh migration):

1. Run a migration end to end — confirm the flow has 5 steps (no Map Entry).
2. On Map Content Fields, confirm all content types show; empty list shows the error state with Continue disabled.

Iteration 2+ (delta / restart):

1. Restart a completed migration (iteration bumps) and confirm the flow now has 6 steps with Map Entry as step 4.
2. Step 3 shows only NEW content types; if none, the friendly "No new content types" state shows with Continue enabled.
3. Step 4 (Map Entry) shows only already-migrated content types that have entries; select entries and click Save — the content type icon turns green.
4. Reload the page — content type icons keep the correct green/blue status without needing to open each one.
5. Walk all 6 steps forward/back — the progress bar doesn't reset, completed steps are navigable, and current_step in the DB reaches 6 on Execute.
6. Start a migration — live logs stream and the Start button is disabled while running.

Entry update data-loss fix:
7. Have an entry that was NOT migrated in iteration 1 — confirm it gets created this iteration (not silently dropped). Entries marked isUpdate with a Contentstack uid get updated.

Tests:
8. cd api && npm test — updateEntryCli.service.test.ts passes.

Expected result: Iteration 1 = 5 steps unchanged; iteration 2+ = 6 steps with correct new/old content type splitting, persistent status icons, no progress-bar resets, and no entry data loss.

📸 Screenshots / Recordings

🔗 Related PRs / Dependencies

✅ Author Checklist

• Branch follows naming convention: feature/, bugfix/, or hotfix/ + 5–30 lowercase chars
• Jira ticket linked above
• Self-reviewed the diff — no debug logs, commented-out code, or TODOs left in
• .env / example.env updated if new environment variables were added — N/A (no new env vars)
• No sensitive credentials or secrets committed
• Existing tests pass locally (npm test)
• New tests written — added updateEntryCli.service.test.ts
• README.md / docs updated if behaviour changed — N/A
• Talisman pre-push scan passes (no secrets flagged)

👀 Reviewer Notes

• The new/old content type split is driven by a single getContentTypes?filter=new|old param + a per-iteration diff on contentTypesMapper.json — no new endpoint.
• Step numbering is iteration-aware in two places that must stay in sync: createStepper() (UI) and migrationSteps.json all_steps (side-nav), plus the backend STEPPER_STEPS / DELTA_STEPPER_STEPS.
• Please double-check the entry-update.utils.ts delete rule — entries are removed from import data only when they have a contentstackEntryUid (exist in CS); never-migrated entries are intentionally kept to be created.

Migration v2 · Docs · Issues